Сессии клиента

Сессия показывает, когда, откуда и каким способом клиент пользовался продуктом. Gigma создаёт её автоматически вместе с Bearer: отдельного запроса для начала сессии нет.

Сессия и Bearer — разные сущности. Bearer разрешает запросы, а сессия хранит историю использования. После простоя сессия может завершиться, но действующий Bearer продолжит работать.

Что записывается в сессию

Для каждого успешного входа Gigma сохраняет:

клиента и Application;
способ входа;
название устройства из поля device;
время начала и последней активности;
активное время;
состояние и причину завершения.

У одного Bearer одновременно не больше одной активной сессии. Если клиент вошёл отдельно на телефоне и ноутбуке, у него будут два Bearer и две параллельные сессии. После долгого перерыва следующий heartbeat создаст новую сессию с тем же токеном.

Как проходит жизненный цикл

Вход. Gigma выдаёт Bearer и создаёт сессию.
Активность. Клиент или backend отправляет heartbeat. Каждый запрос обновляет last_seen_at и активное время.
Простой. Если heartbeat не было 300 секунд, сессия завершается по времени последней активности.
Возврат. Следующий heartbeat с тем же действующим Bearer открывает новую сессию.
Выход или перевыпуск. Gigma завершает текущую сессию с соответствующей причиной.

За один интервал учитывается не больше 180 секунд. Сессии хранятся 180 дней, затем удаляются. При удалении клиента удаляется и его история сессий.

Способы входа

Способ фиксируется при выдаче Bearer и не меняется.

Значение	Что означает
`phone_code`	одноразовый код, полученный звонком на телефон
`email_code`	одноразовый код, полученный на email
`miniapp_max`	подписанный вход из приложения в MAX
`miniapp_telegram`	зарезервировано; безопасный вход по контакту сейчас не поддерживается
`callback_call`	подтверждение номера callback-звонком
`legacy`	Bearer, выданный до появления сессий

Все сценарии описаны на странице «Вход клиента».

Сколько действует Bearer

Способ входа	Срок действия	Права
Одноразовый код на телефон или email, подписанный контакт	один год с момента входа	полный доступ к клиентским методам
Callback-звонок	сутки по умолчанию; значение задаётся проектом	ability `counterparty:access`

Точное время окончания не возвращается при входе. Backend может получить expires_at через introspect.

Просроченный Bearer перестаёт работать сразу. Запись завершённой сессии остаётся в истории до плановой очистки.

Причины завершения

`end_reason`	Когда возникает
`logout`	клиент вышел на текущем устройстве
`logout_all`	клиент вышел со всех устройств, все его Bearer удалены
`idle_timeout`	активности не было дольше 300 секунд
`token_reissued`	callback-вход выдал новый Bearer вместо прежнего

Зачем использовать сессии

Поддержка видит, входил ли клиент, когда был активен и с какого устройства.
Аналитика получает признак «онлайн» и подтверждённое активное время.
Пользователь может завершить текущий вход или выйти со всех устройств.
Команда видит, какие способы входа действительно используются.

Сессия не является правилом доступа. active ничего не говорит об оплате или подписке, а отсутствие активной сессии не означает, что Bearer отозван.

Получение сессий в платформе

Метод предназначен для сотрудников платформы. Он возвращает сводку и историю сессий выбранного клиента.

Получите сессии клиента

Метод: GET
URL: https://api.gigma.ru/api/counterparties/{counterparty}/sessions
Авторизация: Bearer token
Headers: Authorization: Bearer {token}
Успешный ответ: 200

Нужны права view-counterparties, create-counterparties или edit-counterparties. Клиент должен принадлежать проекту сотрудника.

Параметры запроса

page (integer, опционально) — номер страницы, начиная с 1.
per_page (integer, опционально) — размер страницы от 1 до 100, по умолчанию 20.
from (date, опционально) — начало периода по времени старта сессии, формат YYYY-MM-DD.
to (date, опционально) — конец периода в формате YYYY-MM-DD; значение не раньше from.
application_id (integer, опционально) — фильтр по приложению проекта.
auth_method (string, опционально) — один из способов входа из таблицы выше.
status (string, опционально) — active или ended.

Ответ

При успешном запросе API вернёт HTTP 200.

{
    "summary": {
        "last_login_at": "2026-08-18T09:12:00+00:00",
        "last_seen_at": "2026-08-18T10:04:00+00:00",
        "is_online": true,
        "total_duration_seconds": 5400
    },
    "sessions": [
        {
            "id": 128,
            "application": { "id": 275, "name": "Интернет-магазин" },
            "auth_method": "phone_code",
            "device": "iPhone, Safari",
            "status": "active",
            "started_at": "2026-08-18T09:12:00+00:00",
            "last_seen_at": "2026-08-18T10:04:00+00:00",
            "ended_at": null,
            "duration_seconds": 3120,
            "end_reason": null
        }
    ],
    "pagination": {
        "total": 42,
        "per_page": 20,
        "current_page": 1,
        "last_page": 3
    }
}

Описание полей

summary.last_login_at — начало последней сессии с учётом фильтров.
summary.last_seen_at — последняя активность клиента.
summary.is_online — есть ли незакрытая сессия с активностью за последние 300 секунд.
summary.total_duration_seconds — суммарное активное время по выбранным сессиям.
application — приложение сессии. Название сохраняется на момент входа.
device — название устройства, переданное при входе; может быть null.
auth_method — способ входа.
status — active или ended. Сессия без активности дольше 300 секунд показывается как ended с причиной idle_timeout ещё до планового закрытия.
started_at — время начала сессии в ISO 8601.
last_seen_at — время последней активности в ISO 8601.
ended_at (string|null) — время завершения; null у активной сессии.
end_reason (string|null) — logout, logout_all, idle_timeout или token_reissued; null у активной сессии.
duration_seconds (integer) — активное время сессии в секундах.
pagination — данные постраничной выдачи.

Список отсортирован по времени начала: новые сессии идут первыми.

Возможные ошибки

401 — Bearer сотрудника отсутствует или недействителен.
403 — у сотрудника нет прав на клиентов либо клиент принадлежит другому проекту.
404 — клиента с таким идентификатором нет.
422 — фильтры не прошли валидацию: to раньше from, per_page больше 100, неизвестный auth_method или status, приложение не относится к проекту.

Готово: сотрудник получил историю входов, устройств и активности клиента.

Что дальше

Вход клиента — получить Bearer выбранным способом.
Heartbeat клиентской сессии — учитывать активное время.
Проверка Bearer через introspect — проверить токен на backend.